DO NOT MERGE: fix(folders): enforce FolderSearchParams required fields in the canonical constructor (#34154) - #36967

Summary

FolderSearchParams kept its siteId and user null checks in Builder.build(). This moves them into
the canonical constructor, and documents the shape trade-off that made the misplacement easy to miss.

Why the builder could never enforce it

A record's canonical constructor cannot be declared less accessible than the record itself — the
language forbids it. So for a public record there is always a public positional entry point, and
builder() can only ever be a convenience, never a gate:

FolderSearchParams.builder().user(user).build();   // rejected: no siteId
new FolderSearchParams(name, path, false, null, user, ...);   // before: accepted

This is a real difference from the Immutables-based models used elsewhere in this codebase, where the
generated constructor is private (ImportResult → private ImportResult(...)) and the builder
therefore genuinely is the only door. With a record, the invariant has exactly one enforceable home.

What changed

Both checks moved to the canonical constructor. build() now delegates instead of carrying its own copy.

Behaviour is unchanged for existing callers: same exception type (NullPointerException, via
Objects.requireNonNull), same messages ("siteId is required" / "user is required"), and build()
still rejects the same inputs. Nothing in the repository constructs the record directly other than
build() itself, so no call site changes.

The javadoc note

The same commit range documents what validation cannot fix here, because it is the more interesting
half. The record carries eleven flat components, and the count has already grown once
(includePermissions arrived with #36889). Three pairs of adjacent components share a type —
name/path, limit/offset, orderBy/orderDirection — and three more are boolean
(recursive, respectFrontendRoles, includePermissions).

A transposed argument list therefore compiles and silently searches for the wrong thing, or quietly
flips a permission behaviour. Constructor validation does nothing for that: each transposed value is
individually valid, so there is nothing for a check to reject. The grouping that would fix it by typing
instead of by discipline is recorded in the javadoc:

public record FolderSearchParams(
        FolderCriteria criteria,   // name, path, recursive
        Requester requester,       // user, respectFrontendRoles, includePermissions
        PageRequest page) {        // limit, offset, sortColumn, sortDirection
}

Deliberately not applied: this type is in the FolderAPI.searchFolders signature, so reshaping it is
a public API change and belongs in its own PR. Written down so that keeping the flat shape stays a
decision rather than an oversight.

Testing

44 green — 15 unit, 29 integration.

The test that carries the weight is test_directConstruction_enforcesRequiredFields — it exercises the
path a check in build() cannot cover, and would have passed silently before this change. The others
pin what must not have shifted: the same exception and message coming out of the builder, the builder's
defaults, and that the optional components may still be null (name == null is how "no name filter" is
expressed).

doclint is disabled project-wide (parent/pom.xml → <doclint>none</doclint>), so the javadoc carries
no build risk.

Breaking Changes

None for any caller in this repository. Strictly speaking, external code that constructed the record
directly with a null siteId or user would now fail at construction rather than later and elsewhere —
which is the intent, and the type is on a public API, so it is worth stating rather than glossing over.

Context

Groundwork for the Devoxx Belgium 2025 Lunch and Learn (#34154). Its dotCMS half argues about when
records fit this codebase and when they do not, and this type carries both halves of that argument at
once: the invariant belongs on the canonical constructor because it cannot be hidden, and eleven flat
components is the point where a record stops being the right carrier.

This PR fixes: #34154

🤖 Generated with Claude Code